package raft.message;

import raft.message.RaftMessage;

/**
 * Raft消息处理器接口
 * 
 * <p>定义了Raft节点间通信的抽象接口，封装了底层的网络通信细节。
 * 不同的实现可以支持不同的通信方式：</p>
 * <ul>
 *   <li><b>InMemoryMessageHandler</b>: 内存通信，用于单JVM测试</li>
 *   <li><b>NetworkMessageHandler</b>: 网络通信，用于分布式部署</li>
 *   <li><b>其他实现</b>: 可支持不同的序列化和传输协议</li>
 * </ul>
 * 
 * <p><b>设计原则：</b></p>
 * <ul>
 *   <li>同步调用：所有方法都是同步的，调用者负责处理超时和重试</li>
 *   <li>异常处理：实现类应该处理网络异常，返回适当的错误响应</li>
 *   <li>线程安全：实现类必须是线程安全的，支持并发调用</li>
 * </ul>
 * 
 * @author Raft Implementation Team
 * @version 1.0
 * @since 1.0
 */
public interface RaftMessageHandler {
    
    /**
     * 发送投票请求 (RequestVote RPC)
     * 
     * <p>候选者调用此方法向其他节点发送投票请求。</p>
     * 
     * @param nodeId 目标节点ID，不能为null或空
     * @param request 投票请求消息，不能为null
     * @return 投票响应消息；如果目标节点不可达，应返回拒绝投票的响应
     * @throws IllegalArgumentException 如果参数不合法
     */
    RaftMessage.VoteResponse sendVoteRequest(String nodeId, RaftMessage.VoteRequest request);
    
    /**
     * 发送附加日志请求 (AppendEntries RPC)
     * 
     * <p>Leader调用此方法向Follower发送日志复制或心跳消息。</p>
     * 
     * @param nodeId 目标节点ID，不能为null或空
     * @param request 附加日志请求消息，不能为null
     * @return 附加日志响应消息；如果目标节点不可达，应返回失败响应
     * @throws IllegalArgumentException 如果参数不合法
     */
    RaftMessage.AppendEntriesResponse sendAppendEntries(String nodeId, RaftMessage.AppendEntriesRequest request);
} 